home *** CD-ROM | disk | FTP | other *** search
/ Personal Computer World 2009 February / PCWFEB09.iso / Software / Linux / SLAX 6.0.8 / slax-6.0.8.iso / slax / base / 006-devel.lzm / usr / include / dst / dst.h next >
Encoding:
C/C++ Source or Header  |  2008-09-17  |  15.2 KB  |  621 lines
  1. /*
  2.  * Copyright (C) 2004-2006  Internet Systems Consortium, Inc. ("ISC")
  3.  * Copyright (C) 2000-2002  Internet Software Consortium.
  4.  *
  5.  * Permission to use, copy, modify, and distribute this software for any
  6.  * purpose with or without fee is hereby granted, provided that the above
  7.  * copyright notice and this permission notice appear in all copies.
  8.  *
  9.  * THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
  10.  * REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
  11.  * AND FITNESS.  IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
  12.  * INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
  13.  * LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
  14.  * OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
  15.  * PERFORMANCE OF THIS SOFTWARE.
  16.  */
  17.  
  18. /* $Id: dst.h,v 1.1.6.5 2006/01/27 23:57:44 marka Exp $ */
  19.  
  20. #ifndef DST_DST_H
  21. #define DST_DST_H 1
  22.  
  23. /*! \file */
  24.  
  25. #include <isc/lang.h>
  26.  
  27. #include <dns/types.h>
  28.  
  29. ISC_LANG_BEGINDECLS
  30.  
  31. /***
  32.  *** Types
  33.  ***/
  34.  
  35. /*%
  36.  * The dst_key structure is opaque.  Applications should use the accessor
  37.  * functions provided to retrieve key attributes.  If an application needs
  38.  * to set attributes, new accessor functions will be written.
  39.  */
  40.  
  41. typedef struct dst_key        dst_key_t;
  42. typedef struct dst_context     dst_context_t;
  43.  
  44. /* DST algorithm codes */
  45. #define DST_ALG_UNKNOWN        0
  46. #define DST_ALG_RSAMD5        1
  47. #define DST_ALG_RSA        DST_ALG_RSAMD5    /*%< backwards compatibility */
  48. #define DST_ALG_DH        2
  49. #define DST_ALG_DSA        3
  50. #define DST_ALG_ECC        4
  51. #define DST_ALG_RSASHA1        5
  52. #define DST_ALG_HMACMD5        157
  53. #define DST_ALG_GSSAPI        160
  54. #define DST_ALG_HMACSHA1    161    /* XXXMPA */
  55. #define DST_ALG_HMACSHA224    162    /* XXXMPA */
  56. #define DST_ALG_HMACSHA256    163    /* XXXMPA */
  57. #define DST_ALG_HMACSHA384    164    /* XXXMPA */
  58. #define DST_ALG_HMACSHA512    165    /* XXXMPA */
  59. #define DST_ALG_PRIVATE        254
  60. #define DST_ALG_EXPAND        255
  61. #define DST_MAX_ALGS        255
  62.  
  63. /*% A buffer of this size is large enough to hold any key */
  64. #define DST_KEY_MAXSIZE        1280
  65.  
  66. /*%
  67.  * A buffer of this size is large enough to hold the textual representation
  68.  * of any key
  69.  */
  70. #define DST_KEY_MAXTEXTSIZE    2048
  71.  
  72. /*% 'Type' for dst_read_key() */
  73. #define DST_TYPE_KEY        0x1000000    /* KEY key */
  74. #define DST_TYPE_PRIVATE    0x2000000
  75. #define DST_TYPE_PUBLIC        0x4000000
  76.  
  77. /***
  78.  *** Functions
  79.  ***/
  80.  
  81. isc_result_t
  82. dst_lib_init(isc_mem_t *mctx, isc_entropy_t *ectx, unsigned int eflags);
  83. /*%<
  84.  * Initializes the DST subsystem.
  85.  *
  86.  * Requires:
  87.  * \li     "mctx" is a valid memory context
  88.  * \li    "ectx" is a valid entropy context
  89.  *
  90.  * Returns:
  91.  * \li    ISC_R_SUCCESS
  92.  * \li    ISC_R_NOMEMORY
  93.  *
  94.  * Ensures:
  95.  * \li    DST is properly initialized.
  96.  */
  97.  
  98. void
  99. dst_lib_destroy(void);
  100. /*%<
  101.  * Releases all resources allocated by DST.
  102.  */
  103.  
  104. isc_boolean_t
  105. dst_algorithm_supported(unsigned int alg);
  106. /*%<
  107.  * Checks that a given algorithm is supported by DST.
  108.  *
  109.  * Returns:
  110.  * \li    ISC_TRUE
  111.  * \li    ISC_FALSE
  112.  */
  113.  
  114. isc_result_t
  115. dst_context_create(dst_key_t *key, isc_mem_t *mctx, dst_context_t **dctxp);
  116. /*%<
  117.  * Creates a context to be used for a sign or verify operation.
  118.  *
  119.  * Requires:
  120.  * \li    "key" is a valid key.
  121.  * \li    "mctx" is a valid memory context.
  122.  * \li    dctxp != NULL && *dctxp == NULL
  123.  *
  124.  * Returns:
  125.  * \li    ISC_R_SUCCESS
  126.  * \li    ISC_R_NOMEMORY
  127.  *
  128.  * Ensures:
  129.  * \li    *dctxp will contain a usable context.
  130.  */
  131.  
  132. void
  133. dst_context_destroy(dst_context_t **dctxp);
  134. /*%<
  135.  * Destroys all memory associated with a context.
  136.  *
  137.  * Requires:
  138.  * \li    *dctxp != NULL && *dctxp == NULL
  139.  *
  140.  * Ensures:
  141.  * \li    *dctxp == NULL
  142.  */
  143.  
  144. isc_result_t
  145. dst_context_adddata(dst_context_t *dctx, const isc_region_t *data);
  146. /*%<
  147.  * Incrementally adds data to the context to be used in a sign or verify
  148.  * operation.
  149.  *
  150.  * Requires:
  151.  * \li    "dctx" is a valid context
  152.  * \li    "data" is a valid region
  153.  *
  154.  * Returns:
  155.  * \li    ISC_R_SUCCESS
  156.  * \li    DST_R_SIGNFAILURE
  157.  * \li    all other errors indicate failure
  158.  */
  159.  
  160. isc_result_t
  161. dst_context_sign(dst_context_t *dctx, isc_buffer_t *sig);
  162. /*%<
  163.  * Computes a signature using the data and key stored in the context.
  164.  *
  165.  * Requires:
  166.  * \li    "dctx" is a valid context.
  167.  * \li    "sig" is a valid buffer.
  168.  *
  169.  * Returns:
  170.  * \li    ISC_R_SUCCESS
  171.  * \li    DST_R_VERIFYFAILURE
  172.  * \li    all other errors indicate failure
  173.  *
  174.  * Ensures:
  175.  * \li    "sig" will contain the signature
  176.  */
  177.  
  178. isc_result_t
  179. dst_context_verify(dst_context_t *dctx, isc_region_t *sig);
  180. /*%<
  181.  * Verifies the signature using the data and key stored in the context.
  182.  *
  183.  * Requires:
  184.  * \li    "dctx" is a valid context.
  185.  * \li    "sig" is a valid region.
  186.  *
  187.  * Returns:
  188.  * \li    ISC_R_SUCCESS
  189.  * \li    all other errors indicate failure
  190.  *
  191.  * Ensures:
  192.  * \li    "sig" will contain the signature
  193.  */
  194.  
  195. isc_result_t
  196. dst_key_computesecret(const dst_key_t *pub, const dst_key_t *priv,
  197.               isc_buffer_t *secret);
  198. /*%<
  199.  * Computes a shared secret from two (Diffie-Hellman) keys.
  200.  *
  201.  * Requires:
  202.  * \li    "pub" is a valid key that can be used to derive a shared secret
  203.  * \li    "priv" is a valid private key that can be used to derive a shared secret
  204.  * \li    "secret" is a valid buffer
  205.  *
  206.  * Returns:
  207.  * \li    ISC_R_SUCCESS
  208.  * \li    any other result indicates failure
  209.  *
  210.  * Ensures:
  211.  * \li    If successful, secret will contain the derived shared secret.
  212.  */
  213.  
  214. isc_result_t
  215. dst_key_fromfile(dns_name_t *name, dns_keytag_t id, unsigned int alg, int type,
  216.          const char *directory, isc_mem_t *mctx, dst_key_t **keyp);
  217. /*%<
  218.  * Reads a key from permanent storage.  The key can either be a public or
  219.  * private key, and is specified by name, algorithm, and id.  If a private key
  220.  * is specified, the public key must also be present.  If directory is NULL,
  221.  * the current directory is assumed.
  222.  *
  223.  * Requires:
  224.  * \li    "name" is a valid absolute dns name.
  225.  * \li    "id" is a valid key tag identifier.
  226.  * \li    "alg" is a supported key algorithm.
  227.  * \li    "type" is DST_TYPE_PUBLIC, DST_TYPE_PRIVATE, or the bitwise union.
  228.  *          DST_TYPE_KEY look for a KEY record otherwise DNSKEY
  229.  * \li    "mctx" is a valid memory context.
  230.  * \li    "keyp" is not NULL and "*keyp" is NULL.
  231.  *
  232.  * Returns:
  233.  * \li    ISC_R_SUCCESS
  234.  * \li    any other result indicates failure
  235.  *
  236.  * Ensures:
  237.  * \li    If successful, *keyp will contain a valid key.
  238.  */
  239.  
  240. isc_result_t
  241. dst_key_fromnamedfile(const char *filename, int type, isc_mem_t *mctx,
  242.               dst_key_t **keyp);
  243. /*%<
  244.  * Reads a key from permanent storage.  The key can either be a public or
  245.  * key, and is specified by filename.  If a private key is specified, the
  246.  * public key must also be present.
  247.  *
  248.  * Requires:
  249.  * \li    "filename" is not NULL
  250.  * \li    "type" is DST_TYPE_PUBLIC, DST_TYPE_PRIVATE, or the bitwise union
  251.  *          DST_TYPE_KEY look for a KEY record otherwise DNSKEY
  252.  * \li    "mctx" is a valid memory context
  253.  * \li    "keyp" is not NULL and "*keyp" is NULL.
  254.  *
  255.  * Returns:
  256.  * \li    ISC_R_SUCCESS
  257.  * \li    any other result indicates failure
  258.  *
  259.  * Ensures:
  260.  * \li    If successful, *keyp will contain a valid key.
  261.  */
  262.  
  263.  
  264. isc_result_t
  265. dst_key_read_public(const char *filename, int type,
  266.             isc_mem_t *mctx, dst_key_t **keyp);
  267. /*%<
  268.  * Reads a public key from permanent storage.  The key must be a public key.
  269.  *
  270.  * Requires:
  271.  * \li    "filename" is not NULL
  272.  * \li    "type" is DST_TYPE_KEY look for a KEY record otherwise DNSKEY
  273.  * \li    "mctx" is a valid memory context
  274.  * \li    "keyp" is not NULL and "*keyp" is NULL.
  275.  *
  276.  * Returns:
  277.  * \li    ISC_R_SUCCESS
  278.  * \li    DST_R_BADKEYTYPE if the key type is not the expected one
  279.  * \li    ISC_R_UNEXPECTEDTOKEN if the file can not be parsed as a public key
  280.  * \li    any other result indicates failure
  281.  *
  282.  * Ensures:
  283.  * \li    If successful, *keyp will contain a valid key.
  284.  */
  285.  
  286. isc_result_t
  287. dst_key_tofile(const dst_key_t *key, int type, const char *directory);
  288. /*%<
  289.  * Writes a key to permanent storage.  The key can either be a public or
  290.  * private key.  Public keys are written in DNS format and private keys
  291.  * are written as a set of base64 encoded values.  If directory is NULL,
  292.  * the current directory is assumed.
  293.  *
  294.  * Requires:
  295.  * \li    "key" is a valid key.
  296.  * \li    "type" is DST_TYPE_PUBLIC, DST_TYPE_PRIVATE, or the bitwise union
  297.  *
  298.  * Returns:
  299.  * \li    ISC_R_SUCCESS
  300.  * \li    any other result indicates failure
  301.  */
  302.  
  303. isc_result_t
  304. dst_key_fromdns(dns_name_t *name, dns_rdataclass_t rdclass,
  305.         isc_buffer_t *source, isc_mem_t *mctx, dst_key_t **keyp);
  306. /*%<
  307.  * Converts a DNS KEY record into a DST key.
  308.  *
  309.  * Requires:
  310.  * \li    "name" is a valid absolute dns name.
  311.  * \li    "source" is a valid buffer.  There must be at least 4 bytes available.
  312.  * \li    "mctx" is a valid memory context.
  313.  * \li    "keyp" is not NULL and "*keyp" is NULL.
  314.  *
  315.  * Returns:
  316.  * \li    ISC_R_SUCCESS
  317.  * \li    any other result indicates failure
  318.  *
  319.  * Ensures:
  320.  * \li    If successful, *keyp will contain a valid key, and the consumed
  321.  *    pointer in data will be advanced.
  322.  */
  323.  
  324. isc_result_t
  325. dst_key_todns(const dst_key_t *key, isc_buffer_t *target);
  326. /*%<
  327.  * Converts a DST key into a DNS KEY record.
  328.  *
  329.  * Requires:
  330.  * \li    "key" is a valid key.
  331.  * \li    "target" is a valid buffer.  There must be at least 4 bytes unused.
  332.  *
  333.  * Returns:
  334.  * \li    ISC_R_SUCCESS
  335.  * \li    any other result indicates failure
  336.  *
  337.  * Ensures:
  338.  * \li    If successful, the used pointer in 'target' is advanced by at least 4.
  339.  */
  340.  
  341. isc_result_t
  342. dst_key_frombuffer(dns_name_t *name, unsigned int alg,
  343.            unsigned int flags, unsigned int protocol,
  344.            dns_rdataclass_t rdclass,
  345.            isc_buffer_t *source, isc_mem_t *mctx, dst_key_t **keyp);
  346. /*%<
  347.  * Converts a buffer containing DNS KEY RDATA into a DST key.
  348.  *
  349.  * Requires:
  350.  *\li    "name" is a valid absolute dns name.
  351.  *\li    "alg" is a supported key algorithm.
  352.  *\li    "source" is a valid buffer.
  353.  *\li    "mctx" is a valid memory context.
  354.  *\li    "keyp" is not NULL and "*keyp" is NULL.
  355.  *
  356.  * Returns:
  357.  *\li     ISC_R_SUCCESS
  358.  * \li    any other result indicates failure
  359.  *
  360.  * Ensures:
  361.  *\li    If successful, *keyp will contain a valid key, and the consumed
  362.  *    pointer in source will be advanced.
  363.  */
  364.  
  365. isc_result_t
  366. dst_key_tobuffer(const dst_key_t *key, isc_buffer_t *target);
  367. /*%<
  368.  * Converts a DST key into DNS KEY RDATA format.
  369.  *
  370.  * Requires:
  371.  *\li    "key" is a valid key.
  372.  *\li    "target" is a valid buffer.
  373.  *
  374.  * Returns:
  375.  *\li     ISC_R_SUCCESS
  376.  * \li    any other result indicates failure
  377.  *
  378.  * Ensures:
  379.  *\li    If successful, the used pointer in 'target' is advanced.
  380.  */
  381.  
  382. isc_result_t
  383. dst_key_privatefrombuffer(dst_key_t *key, isc_buffer_t *buffer);
  384. /*%<
  385.  * Converts a public key into a private key, reading the private key
  386.  * information from the buffer.  The buffer should contain the same data
  387.  * as the .private key file would.
  388.  *
  389.  * Requires:
  390.  *\li    "key" is a valid public key.
  391.  *\li    "buffer" is not NULL.
  392.  *
  393.  * Returns:
  394.  *\li     ISC_R_SUCCESS
  395.  * \li    any other result indicates failure
  396.  *
  397.  * Ensures:
  398.  *\li    If successful, key will contain a valid private key.
  399.  */
  400.  
  401.  
  402. isc_result_t
  403. dst_key_fromgssapi(dns_name_t *name, void *opaque, isc_mem_t *mctx,
  404.                            dst_key_t **keyp);
  405. /*%<
  406.  * Converts a GSSAPI opaque context id into a DST key.
  407.  *
  408.  * Requires:
  409.  *\li    "name" is a valid absolute dns name.
  410.  *\li    "opaque" is a GSSAPI context id.
  411.  *\li    "mctx" is a valid memory context.
  412.  *\li    "keyp" is not NULL and "*keyp" is NULL.
  413.  *
  414.  * Returns:
  415.  *\li     ISC_R_SUCCESS
  416.  * \li    any other result indicates failure
  417.  *
  418.  * Ensures:
  419.  *\li    If successful, *keyp will contain a valid key and be responsible for
  420.  *    the context id.
  421.  */
  422.  
  423. isc_result_t
  424. dst_key_generate(dns_name_t *name, unsigned int alg,
  425.          unsigned int bits, unsigned int param,
  426.          unsigned int flags, unsigned int protocol,
  427.          dns_rdataclass_t rdclass,
  428.          isc_mem_t *mctx, dst_key_t **keyp);
  429. /*%<
  430.  * Generate a DST key (or keypair) with the supplied parameters.  The
  431.  * interpretation of the "param" field depends on the algorithm:
  432.  * \code
  433.  *     RSA:    exponent
  434.  *         0    use exponent 3
  435.  *         !0    use Fermat4 (2^16 + 1)
  436.  *     DH:    generator
  437.  *         0    default - use well known prime if bits == 768 or 1024,
  438.  *             otherwise use 2 as the generator.
  439.  *         !0    use this value as the generator.
  440.  *     DSA:    unused
  441.  *     HMACMD5: entropy
  442.  *        0    default - require good entropy
  443.  *        !0    lack of good entropy is ok
  444.  *\endcode
  445.  *
  446.  * Requires:
  447.  *\li    "name" is a valid absolute dns name.
  448.  *\li    "keyp" is not NULL and "*keyp" is NULL.
  449.  *
  450.  * Returns:
  451.  *\li     ISC_R_SUCCESS
  452.  * \li    any other result indicates failure
  453.  *
  454.  * Ensures:
  455.  *\li    If successful, *keyp will contain a valid key.
  456.  */
  457.  
  458. isc_boolean_t
  459. dst_key_compare(const dst_key_t *key1, const dst_key_t *key2);
  460. /*%<
  461.  * Compares two DST keys.
  462.  *
  463.  * Requires:
  464.  *\li    "key1" is a valid key.
  465.  *\li    "key2" is a valid key.
  466.  *
  467.  * Returns:
  468.  *\li     ISC_TRUE
  469.  * \li    ISC_FALSE
  470.  */
  471.  
  472. isc_boolean_t
  473. dst_key_paramcompare(const dst_key_t *key1, const dst_key_t *key2);
  474. /*%<
  475.  * Compares the parameters of two DST keys.  This is used to determine if
  476.  * two (Diffie-Hellman) keys can be used to derive a shared secret.
  477.  *
  478.  * Requires:
  479.  *\li    "key1" is a valid key.
  480.  *\li    "key2" is a valid key.
  481.  *
  482.  * Returns:
  483.  *\li     ISC_TRUE
  484.  * \li    ISC_FALSE
  485.  */
  486.  
  487. void
  488. dst_key_free(dst_key_t **keyp);
  489. /*%<
  490.  * Release all memory associated with the key.
  491.  *
  492.  * Requires:
  493.  *\li    "keyp" is not NULL and "*keyp" is a valid key.
  494.  *
  495.  * Ensures:
  496.  *\li    All memory associated with "*keyp" will be freed.
  497.  *\li    *keyp == NULL
  498.  */
  499.  
  500. /*%<
  501.  * Accessor functions to obtain key fields.
  502.  *
  503.  * Require:
  504.  *\li    "key" is a valid key.
  505.  */
  506. dns_name_t *
  507. dst_key_name(const dst_key_t *key);
  508.  
  509. unsigned int
  510. dst_key_size(const dst_key_t *key);
  511.  
  512. unsigned int
  513. dst_key_proto(const dst_key_t *key);
  514.  
  515. unsigned int
  516. dst_key_alg(const dst_key_t *key);
  517.  
  518. isc_uint32_t
  519. dst_key_flags(const dst_key_t *key);
  520.  
  521. dns_keytag_t
  522. dst_key_id(const dst_key_t *key);
  523.  
  524. dns_rdataclass_t
  525. dst_key_class(const dst_key_t *key);
  526.  
  527. isc_boolean_t
  528. dst_key_isprivate(const dst_key_t *key);
  529.  
  530. isc_boolean_t
  531. dst_key_iszonekey(const dst_key_t *key);
  532.  
  533. isc_boolean_t
  534. dst_key_isnullkey(const dst_key_t *key);
  535.  
  536. isc_result_t
  537. dst_key_buildfilename(const dst_key_t *key, int type,
  538.               const char *directory, isc_buffer_t *out);
  539. /*%<
  540.  * Generates the filename used by dst to store the specified key.
  541.  * If directory is NULL, the current directory is assumed.
  542.  *
  543.  * Requires:
  544.  *\li    "key" is a valid key
  545.  *\li    "type" is either DST_TYPE_PUBLIC, DST_TYPE_PRIVATE, or 0 for no suffix.
  546.  *\li    "out" is a valid buffer
  547.  *
  548.  * Ensures:
  549.  *\li    the file name will be written to "out", and the used pointer will
  550.  *        be advanced.
  551.  */
  552.  
  553. isc_result_t
  554. dst_key_sigsize(const dst_key_t *key, unsigned int *n);
  555. /*%<
  556.  * Computes the size of a signature generated by the given key.
  557.  *
  558.  * Requires:
  559.  *\li    "key" is a valid key.
  560.  *\li    "n" is not NULL
  561.  *
  562.  * Returns:
  563.  *\li    #ISC_R_SUCCESS
  564.  *\li    DST_R_UNSUPPORTEDALG
  565.  *
  566.  * Ensures:
  567.  *\li    "n" stores the size of a generated signature
  568.  */
  569.  
  570. isc_result_t
  571. dst_key_secretsize(const dst_key_t *key, unsigned int *n);
  572. /*%<
  573.  * Computes the size of a shared secret generated by the given key.
  574.  *
  575.  * Requires:
  576.  *\li    "key" is a valid key.
  577.  *\li    "n" is not NULL
  578.  *
  579.  * Returns:
  580.  *\li    #ISC_R_SUCCESS
  581.  *\li    DST_R_UNSUPPORTEDALG
  582.  *
  583.  * Ensures:
  584.  *\li    "n" stores the size of a generated shared secret
  585.  */
  586.  
  587. isc_uint16_t
  588. dst_region_computeid(const isc_region_t *source, unsigned int alg);
  589. /*%<
  590.  * Computes the key id of the key stored in the provided region with the
  591.  * given algorithm.
  592.  *
  593.  * Requires:
  594.  *\li    "source" contains a valid, non-NULL region.
  595.  *
  596.  * Returns:
  597.  *\li     the key id
  598.  */
  599.  
  600. isc_uint16_t
  601. dst_key_getbits(const dst_key_t *key);
  602. /*
  603.  * Get the number of digest bits required (0 == MAX).
  604.  *
  605.  * Requires:
  606.  *    "key" is a valid key.
  607.  */
  608.  
  609. void
  610. dst_key_setbits(dst_key_t *key, isc_uint16_t bits);
  611. /*
  612.  * Set the number of digest bits required (0 == MAX).
  613.  *
  614.  * Requires:
  615.  *    "key" is a valid key.
  616.  */
  617.  
  618. ISC_LANG_ENDDECLS
  619.  
  620. #endif /* DST_DST_H */
  621.